Skip to main content

Troubleshooting 502 Bad Gateway Errors

A 502 Bad Gateway error typically occurs when the entry point (Cloudflare, Nginx, or a Load Balancer) is unable to connect to the backend Docusaurus service. In your Docker environment, this usually means the container is either down, still starting up, or has crashed due to a configuration error.

1. The Startup Lag (Most Common)​

The Problem​

When you run docker restart docusaurus, the site does not come back online instantly. Your container is configured to perform a full build every time it starts:

  1. npm install (Syncing dependencies)
  2. npm run build (Generating static HTML/JS)
  3. npm run serve (Starting the web server)

During steps 1 and 2, the web server is not yet running, so any request to the site returns a 502 error.

The Solution​

Wait. Depending on the number of documents, the build can take anywhere from 1 to 5 minutes.

  • Check progress with: sudo docker logs -f docusaurus
  • Once you see [SUCCESS] Serving "build" directory, the 502 error will disappear.

2. Resource Exhaustion (Build Stalls)​

The Problem​

Docusaurus builds (specifically the Webpack/Babel compilation) are extremely CPU and memory intensive.

  • Symptoms: The site stays 502 for more than 10 minutes, and docker stats shows the container stuck at 100% CPU or hitting its memory limit.
  • Cause: If the container is limited to 1GB or 2GB of RAM, large sites or complex plugins (like search) will cause the process to hang or be killed by the OOM (Out Of Memory) killer.

The Solution​

Increase the allocation in your deployment script or docker-compose.yml:

# Recommended limits for stable builds
--cpus="3" 
--memory="8g"

Technical Insight​

Docusaurus v3+ uses worker threads for image processing and static site generation. Giving it more CPUs directly translates to faster build times and fewer "bridge timeout" errors.

3. The Restart Loop (Invalid Configuration)​

The Problem​

If there is a syntax error in your configuration or a missing file that is referenced in the Navbar, Docusaurus will fail to build and the container will exit. Because of the --restart unless-stopped policy, it will immediately try again, creating a loop.

How to Diagnose​

Watch the logs for specific error strings:

sudo docker logs docusaurus --tail 200 | grep -iE "error|fail|not found"

Common Errors:​

  • Error: Couldn't find any doc with id "...": You have a link in docusaurus.config.js or sidebars.js that points to a file you renamed or deleted.
  • SyntaxError: ...: A missing comma or bracket in docusaurus.config.js.

4. Networking & Port Mismatch​

The Problem​

If the container reports that it is "Serving", but you still see a 502, there may be a mismatch between the container's internal port and the external proxy.

Verification Steps​

  1. Check Port: Ensure Docusaurus is listening on 0.0.0.0 (not localhost) and port 3000.
    • Your package.json should have: "serve": "docusaurus serve --host 0.0.0.0 --port 3000"
  2. Check Network: Ensure the container is on the same Docker network as your proxy/tunnel: 
    sudo docker inspect docusaurus --format '{{.NetworkSettings.Networks}}'

Detailed Troubleshooting Checklist​

Follow these steps in order when you see a 502 error:

Step 1: Check Container Status​

sudo docker ps -a | grep docusaurus
  • Status Up X seconds (restarting): You have a configuration error. Go to Step 2.
  • Status Up X minutes: The site might still be building. Go to Step 2.
  • Status Exited: The container crashed. Try sudo docker start docusaurus.

Step 2: Follow Live Logs​

sudo docker logs -f docusaurus
  • Are you seeing npm install? (Wait)
  • Are you seeing [webpackbar] Compiling? (Wait)
  • Did it end with Error: ...? (Fix the code error)
  • Did it end with Serving "build" directory? (Site should be up)

Step 3: Check System Resources​

sudo docker stats docusaurus --no-stream
  • Is Memory Usage close to the Limit? (Increase RAM)
  • Is CPU persistently at 100%+? (Normal during build, but shouldn't last forever)

Step 4: Verify Content References​

If the build fails 80% of the way through:

  • Check docusaurus.config.js for broken docId references.
  • Verify that all files listed in sidebars.js actually exist.

Prevention & Best Practices​

  1. Use Specific Node Versions: Avoid node:latest. Use node:lts for stability.
  2. Pre-validate Changes: If possible, run npm run build locally before pushing changes to the server.
  3. Monitor Disk Space: A full disk will prevent Docker from creating new build artifacts, leading to silent build failures.
  4. Graceful Hiding: Don't delete files to hide them from the sidebar; use sidebar_class_name: hidden in the markdown frontmatter instead.

Management Reference​

CommandPurpose
sudo docker logs -f docusaurusWatch the build progress
sudo docker restart docusaurusTrigger a fresh build
sudo docker stats docusaurusMonitor RAM/CPU usage
sudo docker exec -it docusaurus shAccess files inside the container